<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
   "http://www.w3.org/TR/html4/strict.dtd">

<html lang="en">
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
	<title>PDoc</title>
	<meta name="generator" content="TextMate http://macromates.com/">
	<meta name="author" content="Tobie Langel">
	<!-- Date: 2008-02-25 -->
	<link rel="stylesheet" href="/stylesheets/reset.css" type="text/css" media="screen" charset="utf-8">
	<link rel="stylesheet" href="/stylesheets/main.css" type="text/css" media="screen" title="no title" charset="utf-8">
	
</head>
<body>
	<div id="wrapper">
		<div id="header">
			<h1><a href="/"><img src="/images/pdoc.jpg" alt="PDoc" /></a></h1>
		</div>
		<div id="navigation">
			<ul>
				<li><a href="/documentation.html">documentation</a></li>
				<li><a href="http://github.com/tobie/pdoc/tree/master">source code</a></li>
				<li><a href="/doc/index.html">rdoc</a></li>
				<li><a href="http://prototype.lighthouseapp.com/projects/8889-pdoc/">bug tracker</a></li>
				<li><a href="http://groups.google.com/group/pdoc">mailing list</a></li>
			</ul>
		</div>
		<div id="content">
			<h1>PDoc</h1>

			<p>PDoc is an inline comment parser and JavaScript documentation generator written in Ruby. It is designed for documenting <a href="http://prototypejs.org">Prototype</a> and Prototype-based libraries.</p>

			<p>PDoc uses <a href="http://treetop.rubyforge.org/">Treetop</a>, a Ruby-based DSL for text parsing and interpretation, and its own ActionView-inspired, ERB-based templating system for HTML generation. Other documentation generators (e.g., DocBook XML) are planned.</p>

			<p>Unlike other inline-doc parsers, PDoc does not rely on the JavaScript source code at all; it only parses the comments. This approach, though slightly more verbose, is much better at generating consistent, reliable documentation, and avoids the headaches encountered when documenting highly dynamic languages.</p>

			<h2>Installation</h2>

			<p>PDoc depends on Rake, <a href="http://maruku.rubyforge.org/">Maruku</a>, and treetop, all of which can be obtained through RubyGems:</p>

			<pre><code>gem install rake maruku treetop
			</code></pre>

			<p>Maruku is a more solid alternative to BlueCloth and is compatible with Ruby 1.9.1.</p>

			<h2>Usage</h2>

			<p>For hints on how to run PDoc on the command line, consult the built-in Rake tasks (in <code>Rakefile</code>) and the <code>PDoc::Runner</code> class (in <code>lib/pdoc/runner.rb</code>).</p>

			<h2>How it works</h2>

			<p>The process of turning inline PDoc comments into a human-friendly document has two phases.</p>

			<h3>Parsing phase</h3>

			<p>In this phase, the source files are scanned for PDoc comments, then parsed with the Ruby files generated from the Treetop language grammar. The product of this phase is a tree full of specialized classes, all of which inherit from <code>Treetop::Runtime::SyntaxNode</code>.</p>

			<p>The root of the tree is an instance of <code>Documentation::Doc</code>. It comprises one or more instances of <code>Documentation::Section</code>; which in turn comprise language elements like namespaces, classes, constants, etc., all of which have class representations.</p>

			<h3>Rendering phase</h3>

			<p>Next, PDoc asks a <em>generator</em> how to translate this abstract tree into a hierarchical document. The default generator outputs organized HTML in a manner similar to <a href="http://rdoc.sourceforge.net/" title="RDoc - Document Generator for Ruby Source">RDoc</a>&#8217;s.</p>

			<p>The HTML generator (<code>PDoc::Generators::Html</code>) has associated <em>templates</em> (in the <code>templates</code> directory) that accept syntax nodes and echo their metadata onto the page using <a href="http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/index.html" title="erb: Ruby Standard Library Documentation">ERB</a>. Templates are modular, so it&#8217;s quite easy to apply a custom &#8220;skin&#8221; to one&#8217;s documentation pages.</p>

			<p>Furthermore, generators themselves are modular; PDoc can, theoretically, parse once and render to several different targets (HTML, <a href="http://www.docbook.org/" title="DocBook.org">DocBook XML</a>, CHM, PDF, even <a href="http://www.scriptdoc.org/" title="ScriptDoc.org: Dynamic Language Documentation">ScriptDoc</a>.) We hope many such generators will exist in the future.</p>
			
			<div id="twitter_div">
				<h2 class="twitter-title">Twitter Updates</h2>
				<ul id="twitter_update_list"></ul>
			</div>
		</div>
		<div id="sidebar">
		
		</div>
		<div id="footer">
			<p>&copy; 2008 Tobie Langel. PDoc logo &copy; 2008 Sam Stephenson.</p>
		</div>
	</div>
	<script type="text/javascript" src="http://twitter.com/javascripts/blogger.js"></script>
	<script type="text/javascript" src="http://twitter.com/statuses/user_timeline/pdoc.json?callback=twitterCallback2&count=5"></script>
</body>
</html>
